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Abstract 


The Sensor Measurement Lists (SenML) media type supports the indication of units for a 
quantity represented. This short document registers a number of additional unit names in the 
IANA registry for units in SenML. It also defines a registry for secondary units that cannot be in 
SenML's main registry, as they are derived by linear transformation from units already in that 
registry. 
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1. Introduction 


The Sensor Measurement Lists (SenML) [RFC8428] media type supports the indication of a unit, 
using the SenML field "u", for the quantity given as a data value in a SenML record. For this 
purpose, SenML defines an IANA registry of defined unit names and their meanings; in the 
present document, we call the unit names registered there "primary unit names". 


This short document registers a number of additional units in the IANA registry for units in 
SenML that appear to be necessary for further adopting SenML in other Standards Development 
Organizations (SDOs). 


The document also defines a registry for secondary unit names that cannot be in SenML's main 
registry, as they are derived by linear transformation from units already in that registry. 
Although SenML version 10 [RFC8428] does not provide for the direct use of these secondary 
units, future support is intended via the use of SenML extension mechanisms, one of which is 
proposed in [SENML-VERSIONS]. 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD 
NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to 
be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in 
all capitals, as shown here. 
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2. New Primary Units 


June 2020 


IANA has assigned new units in the "SenML Units" subregistry of the "Sensor Measurement Lists 


(SenML)" registry [[ANA.SENML] (as defined in [RFC8428]): 


Symbol Description 


B Byte (information content) 

VA volt-ampere (Apparent Power) 

VAs volt-ampere second (Apparent Energy) 

var volt-ampere reactive (Reactive Power) 

vars volt-ampere-reactive second (Reactive Energy) 

J/m joule per meter (Energy per distance) 

kg/m3 kilogram per cubic meter (mass density, mass 
concentration) 

deg degree (angle)* 


Table 1: New Units Registered for SenML 


2.1. Rationale 


Type 
float 
float 
float 
float 
float 
float 


float 


float 


Reference 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


SenML [RFC8428] takes the position that unscaled SI units should always be used. However, 
SenML makes one exception: The degree Celsius (as Cel) is allowed as an alternative to the K 


(Kelvin). 


This document takes the position that the same should apply to a small number of alternative 


units in wide use: 


The Byte: [IEC-80000-13] defines both the bit (item 13-9.b) and the byte (item 13-9.c, also called 
octet) as alternative names for the coherent unit used for dimensionless quantities, for the 
purpose of giving storage capacity and related quantities. While the name octet is 
associated with the symbol o, this is in wide use only in French-speaking countries. 
Globally more widespread is the symbol B for byte, even though B is already taken in SI for 
bel. [RFC8428] therefore registers dB as the SenML unit for logarithmic relative power, 
leaving B free for the usage proposed here. While this is potentially confusing, the 
situation is widely understood in engineering circles and is unlikely to cause actual 


problems. 
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The Volt-Ampere: [IEC-80000-6] defines the volt ampere (VA) (item 6-57.a) as a unit for apparent 
power; items 6-59.a, 6-60.a, and 6-61.a also use the unit for complex, reactive, and non- 
active power. 


The Volt-Ampere Reactive: [IEC-80000-6] item 6-60.b defines the volt-ampere reactive (var) as 
an alternative (and fully equivalent) unit to VA specifically for reactive power (with the 
primary unit VA); it has become clear that there is strong interest in using this unit 
specifically for the imaginary content of complex power, i.e., reactive power [IEEE-1459]. 


The Joule per meter is not a traditional electromagnetic unit. It and its scaled derivatives (in 
particular Wh/km) are used to describe the energy expended for achieving motion over a given 
distance, e.g., as an equivalent for electrical cars of the inverse of "mileage". 


The unit "degree" is in wide use in practice for plane angles (as in heading, bearing, etc.). It is 
marked with an asterisk because the preferred coherent SI unit is radian ("rad"). 


3. New Registry for Secondary Units 


IANA has created a "Secondary Units" subregistry in the "Sensor Measurement Lists (SenML)" 
registry [[ANA.SENML] defined in [RFC8428]. 


The registry has six columns: 


e Secondary Unit: a newly registered name allocated within the same namespace as SenML 
units 


e Description: a short description (usually just the expansion of an abbreviation) 
e SenML Unit: an existing SenML unit from the SenML Units registry 


e Scale, Offset: two rational numbers, expressed in decimal (optionally, with a decimal 
exponent given) or as a fraction represented using a "/" character to separate numerator and 
denominator 


e Reference: where the entry comes from 


Quantities expressed in the secondary unit can be converted into the SenML unit by first 
multiplying their value with the scale number and then adding the offset, yielding the value in 
the given SenML unit. 


The initial content ofthe "Secondary Units" subregistry is provided in Table 2: 


Secondary Description SenML Scale Offset Reference 
Unit Unit 

ms millisecond S 1/1000 0 RFC 8798 
min minute S 60 0 RFC 8798 
h hour s 3600 0 RFC 8798 
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Secondary 
Unit 


MHz 
kW 
kVA 
kvar 
Ah 
Wh 
kWh 
varh 
kvarh 
kVAh 
Wh/km 
KiB 
GB 
Mbit/s 
B/s 
MB/s 
mV 
mA 
dBm 


ug/m3 


mm/h 
m/h 


ppm 
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Description 


megahertz 

kilowatt 
kilovolt-ampere 
kilovar 

ampere-hour 
watt-hour 
kilowatt-hour 
var-hour 
kilovar-hour 
kilovolt-ampere-hour 
watt-hour per kilometer 
kibibyte 

gigabyte 

megabit per second 
byte per second 
megabyte per second 
millivolt 

milliampere 

decibel (milliwatt) 


microgram per cubic 
meter 


millimeter per hour 
meter per hour 


parts per million 


var 


Standards Track 


Scale 


1000000 
1000 
1000 
1000 
3600 
3600 

3600000 
3600 

3600000 

3600000 

3.6 
1024 
1e9 

1000000 

8 
8000000 
1/1000 
1/1000 
1 


1e-9 


1/3600000 
1/3600 


1e-6 


Offset 


June 2020 


Reference 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 


RFC 8798 
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Secondary Description SenML Scale Offset Reference 
Unit Unit 

/100 percent (Note 1) / 1/100 0 RFC 8798 
/1000 permille / 1/1000 0 _RFC8798 
hPa hectopascal Pa 100 0 RFC 8798 
mm millimeter m 1/1000 0 RFC 8798 
cm centimeter m 1/100 0 RFC 8798 
km kilometer m 1000 0 RFC 8798 
km/h kilometer per hour m/s 1/3.6 0 RFC 8798 


Table 2: Secondary Units Registered for SenML 


Note 1: This registration does not use the obvious name "%" because this name has 
been taken in [RFC8428] already, where it is a NOT RECOMMENDED synonym for "/" 
(unity) for legacy reasons. Note that the presence of both "%" and "/100" with 
different meanings is likely to create confusion, so the present document adds some 
weight to the recommendation against using the counterintuitive unit name "%". 


Example: The value of a quantity given as 100 ms is first multiplied by 1/1000, yielding the 
number 0.1, and the offset 0 is then added, yielding the number 0.1 again, leading to a quantity of 
0.1 s. The value of a quantity given as 10 dBm is first multiplied by 1, yielding the number 10, and 
the offset -30 is then added, yielding the number -20, leading to a quantity of -20 dBW. 


New entries can be added to the registration by Expert Review as defined in [RFC8126]. Experts 
should exercise their own good judgment, with the same guidelines as used for SenML units 
(Section 12.1 of [RFC8428]), but without applying rules 4, 5, and 8. Note that rule 7 limits the use 
of what could be understood as prefixes on their own, not the use of prefixes inside secondary 
unit names. Guidelines to the difference between units (which can go into the registry) and 
quantities (which cannot) are widely available; see, for instance, [RS] and [BIPM]. 


As of SenML version 10 [RFC8428], SenML packs are limited to using primary units in "u" fields. 
The use of primary units enables direct comparison of measurements from different sources. 
Also, it facilitates implementations that trigger on the presence of a quantity in a certain unit, 
without the need to track any additional secondary units that may be registered for this quantity. 


Where the benefits of directly using a secondary unit in a SenML pack outweigh the above 
considerations, the use of secondary units in "u" fields MAY be enabled by indicating a new 
SenML version that specifically allows this and/or by using a field with a label name that ends 
with the "_" character ("must-understand" field) whose definition specifically allows this. The 
definition of these versions and fields is outside the scope of the present specification; one such 
definition is proposed in [SENML-VERSIONS]. 
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4. Operational Considerations 


The "Secondary Units" subregistry is expected to grow at a faster pace than the subregistry of 
primary unit names. It also is amenable to automatic interpretation, by making use of the scale 
and offset columns. 


Implementers may be tempted to equip each instance of their systems with code to download 
new versions of the registry from IANA frequently in order to be able to make use of newly 
defined secondary unit names. This can create high load at IANA and a potential single point of 
failure. Instead of pulling the registry in each individual instance of the code, the software 
update mechanism (or a similar mechanism that leads to less frequent IANA visits) SHOULD be 
used to disseminate updated units registries obtained from IANA towards the instances via 
common repositories. 


5. Security Considerations 


The security considerations of [RFC8428] apply. 


The introduction of new measurement units poses no additional security considerations except a 
potential for additional confusion about the proper unit to use and the risk that an 
implementation based on the assumption described in the penultimate paragraph of Section 3 no 
longer works properly. However, an implementation processing a pack while making use of 
secondary units is guaranteed to have been developed with an awareness of the risks of having 
multiple units available for the same logical type. In any case, the existing risk of an existing 
SenML implementation not understanding a unit that was not in the initial registry content 
provided in [RFC8428] is unchanged, and implementations are warned properly about the 
potential use of secondary units by the need for a must-understand field or an updated version 
field. 


6. IANA Considerations 


See Section 2 and Section 3. 
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